Saltar al contenido principal

Ficha técnica

Alcances necesarios​

El token para consumir la API de Cobros debe ser generado usando el Authorization Code.

El alcance openid es obligatorio. Permite consultar el perfil del usuario BTG con acceso a la cuenta.

Es necesario incluir el siguiente alcance:

AlcanceDescripción
brn:btg:empresas:banking:collectionsPermite la consulta y gestión de cobros
brn:btg:empresas:banking:collections.readonlyPermite solo la consulta de cobros

Recursos Disponibles​

Con esta API es posible emitir cobros en formato de boleto tradicional, boleto híbrido, o PIX. Además, es posible configurar en la solicitud una serie de parámetros como intereses, multas, fechas de vencimiento y límite de pago, entre otros.

Verifique los payloads de creación en Crear Cobro.

Boleto tradicional​

La creación de un boleto tradicional se define por la propiedad type y ocurre cuando esta asume el valor BANKSLIP.

{
  "type":"BANKSLIP",
  "amount":10,
  
//Restante do boleto...
}

Boleto híbrido​

La creación de un boleto híbrido se define por la propiedad type y ocurre cuando esta asume el valor BANKSLIP_QRCODE. El boleto híbrido posee toda la estructura de un boleto tradicional, pero va acompañado de un QR Code para pago vía PIX.

Esta modalidad permite la utilización de la jornada 4 del PIX Automático, en caso de que el objeto.

{
  "type":"BANKSLIP_QRCODE",
  "amount":10,
  
//Restante do boleto híbrido...
}

PIX Cobrança QR Code con fecha de vencimiento​

La creación de un PIX Cobrança con fecha de vencimiento se define por la propiedad type y ocurre cuando esta asume el valor DUE_DATE_QRCODE.

{
  "type":"DUE_DATE_QRCODE",
  "amount":10,
  
//Restante do PIX Cobrança...
}

Especificidades​

Utilización de la jornada 4 del PIX Automático​

❗️ Importante

La creación de la autorización y, en consecuencia, el inicio de la jornada 4 ocurrirá SOLAMENTE SI el pago del boleto se realiza a través del QR Code. Otros métodos de pago del boleto no iniciarán la jornada de PIX Automático.

La jornada 4 del PIX Automático puede utilizarse solamente en la emisión de boletos híbridos.

Para activar la jornada, es necesario crear un boleto híbrido y adicionalmente pasar un objeto automaticPixDetails como se muestra en el ejemplo:

{
  "type": "BANKSLIP_QRCODE",
  "automaticPixDetails": {
    "period": "ANNUALLY",
    "retryPolicy": "ACCEPT_3R_7D",
    "contract": "54872120205AASS12",
    "initialDate": "2025-04-18"
  }
	//Restante do payload do boleto...
}

Intereses porcentuales​

El campo de intereses en la opción porcentual se cobra diariamente después del vencimiento del cobro, pero el valor porcentual debe configurarse en relación con lo que se desea cobrar mensualmente.

Por ejemplo, si desea cobrar 0.03% de intereses por día, se debe realizar el post con el valor porcentual de 1%.

{
 //restante do payload do boleto
	"interests": {
    "arrears": {
      "type": "PERCENTAGE",
      "value": 1
    }
	},
	//restante do payload do boleto
}

Cabe destacar que los intereses se cobran por días corridos, por lo que se agregaría 0,03% de intereses incluso en fines de semana y feriados.

Estado del cobro​

Un cobro puede tener distintos estados:

StatusDescripción
CREATEDCobro emitido
PAIDCobro pagado
CANCELEDCobro cancelado
EXPIREDCobro vencido
PROCESSINGCobro en procesamiento
FAILEDFalla en la emisión del cobro
UPDATEDCobro actualizado
UPDATINGCobro en actualización
CANCEL_FAILEDFalla en la cancelación del cobro
RETURNEDCobro reversado
CANCELINGCobro en cancelación

Eventos de webhook​

Los payloads disponibles a continuación representan el contenido del campo data.

EventoDescripción
collections.createdCobro creado.
collections.paidCobro pagado.
collections.expiredCobro expirado.
colections.cancelledCobro cancelado.

collections.created​

{
    "amount": 4620,
    "origin": "APP",
    "dueDate": "2025-10-07",
    "overDueDate": "2026-02-04",
    "type": "BANKSLIP",
    "payer": {
        "address": {
            "number": "11111",
            "zipCode": "111111111",
            "city": "VOLTA REDONDA",
            "street": "RUA",
            "state": "RJ",
            "neighborhood": "JARDIM AMÁLIA"
        },
        "taxId": "21342341243234",
        "name": "NOME",
        "personType": "J"
    },
    "floatingInDays": 1,
    "payee": {
        "branchCode": "50",
        "bankCode": "208",
        "number": "12342134234",
        "taxId": "2123421400103",
        "name": "NOME",
        "personType": "J"
    },
    "installmentNumber": 1,
    "createdAt": "2025-08-08T18:35:25.000Z",
    "totalInstallments": 1,
    "timelineException": false,
    "discounts": [
        {
            "type": "NOT_APPLICABLE",
            "value": 0
        }
    ],
    "interest": {
        "type": "NOT_APPLICABLE",
        "value": 0
    },
    "fine": {
        "type": "NOT_APPLICABLE",
        "value": 0
    },
    "automaticBadCreditException": false,
    "anticipation": {
        "isAnticipated": false
    },
    "correlationId": "new-bill",
    "detail": {
        "documentNumber": "5269/3",
        "externalId": "5edb5555-54c1-4ab7-960e-f54055555d212",
        "ourNumber": "13752155718125475",
        "barCode": "555555543213400000500155755555505224880",
        "digitableLine": "20812555555555806112270000462000"
    },
    "collectionId": "555555-7dcd-4ab9-bdd1-555555b4",
    "updatedAt": "2025-08-08T18:35:25.000Z",
    "status": "CREATED"
}

collections.paid​

{
    "amount": 9200,
    "origin": "WEB",
    "dueDate": "2025-08-12",
    "overDueDate": "2025-12-10",
    "type": "BANKSLIP_QRCODE",
    "payer": {
        "address": {
            "number": "11111",
            "zipCode": "521341240",
            "city": "Recife",
            "street": "RUA",
            "state": "PE",
            "neighborhood": "Tamarineira",
            "complement": "até 3514/3515"
        },
        "taxId": "01324124321464",
        "name": "NOME",
        "personType": "J"
    },
    "payee": {
        "branchCode": "50",
        "bankCode": "208",
        "number": "123421424",
        "taxId": "1234214214",
        "name": "NOME",
        "personType": "J"
    },
    "createdAt": "2025-06-13T21:36:06.000Z",
    "timelineException": false,
    "discounts": [
        {
            "type": "NOT_APPLICABLE",
            "value": 0
        }
    ],
    "amountPaid": 9200,
    "interest": {
        "type": "PERCENTAGE_PER_MONTH",
        "value": 8,
        "startDate": "2025-08-13"
    },
    "fine": {
        "type": "NOT_APPLICABLE",
        "value": 0
    },
    "automaticBadCreditException": false,
    "anticipation": {
        "anticipationDate": "2025-06-16",
        "isAnticipated": true
    },
    "settledAt": "2025-08-08",
    "paidAt": "2025-08-08",
    "paymentMethod": "QRCODE",
    "correlationId": "new-bill",
    "detail": {
        "documentNumber": "28045",
        "externalId": "644444ce2-4444-40e4-8e4f-144444444",
        "ourNumber": "84306546310566684",
        "barCode": "2012342142148405378560",
        "digitableLine": "201234124124124124920000",
        "emv": "00020101021226960014br.gov.bcb.pix2574api.developer.btgpactual.com/v1/p/v2/cobv/4444447a95fc5442ca144444830664479d524444449865802BR5925DMH - TESTE6009SAO PAULO61080453813362070503***630426B7"
    },
    "collectionId": "444444e81-6cef-4bf7-44444-4240309f67d5",
    "updatedAt": "2025-08-08T18:34:32.000Z",
    "status": "PAID"
}

collections.expired​

{
  "collectionId": "be9ed6e9-4444-4f8a-8c8a-ef4441ad44b6",
  "createdAt": "2025-03-08T06:20:49.341Z",
  "amount": 487.25,
  "batchId": "444444ce8-1611-4284-a541-7af4444444a",
  "deliveryMediums": [],
  "type": "BANKSLIP",
  "payee": {
    "name": "NAME",
    "bankCode": "208",
    "branchCode": "1",
    "number": "004444445",
    "personType": "J",
    "taxId": "52664444444435"
  },
  "updatedAt": "2025-03-08T06:20:53.000Z",
  "origin": "CNAB",
  "payer": {
    "taxId": "4444446153",
    "name": "NAME",
    "personType": "F",
    "address": {
      "city": "S.CAETANO SUL",
      "number": "83",
      "state": "SP",
      "street": "RUA SAMUEL KLEIN",
      "zipCode": "09510125",
      "neighborhood": "CENTRO"
    }
  },
  "status": "EXPIRED",
  "correlationId": "54444444140049350804",
  "badCredit": {},
  "anticipation": { "isAnticipated": false },
  "detail": {
    "externalId": "e44444-62ab-46c8-8b5b-4444443fe61",
    "barCode": "208941144444410000058465444444090",
    "digitableLine": "208444444444071090441135044444425",
    "ourNumber": "00000444444",
    "documentNumber": "000000000000000"
  },
  "interest": {
    "startDate": "2025-07-08",
    "type": "PERCENTAGE_PER_MONTH",
    "value": 9.96
  },
  "fine": { "startDate": "2025-07-08", "type": "PERCENTAGE", "value": 4 },
  "discounts": [ { "limitDate": "2025-07-02", "type": "PERCENTAGE", "value": 1.5 } ],
  "overDueDate": "2025-08-06",
  "dueDate": "2025-07-07",
  "installmentNumber": 1,
  "totalInstallments": 1,
  "automaticBadCreditException": false,
  "timelineException": false
}

collections.cancelled​

{
    "amount": 2.97,
    "origin": "WEB",
    "dueDate": "2025-12-13",
    "description": "DESCRIÇÃO",
    "overDueDate": "2026-12-13",
    "type": "BANKSLIP_QRCODE",
    "payer": {
        "taxId": "17584193773",
        "name": "Carlos Caliman",
        "personType": "F"
    },
    "floatingInDays": 1,
    "payee": {
        "branchCode": "50",
        "bankCode": "208",
        "number": "0107444444",
        "taxId": "474444444108",
        "name": "NOME",
        "personType": "J"
    },
    "installmentNumber": 1,
    "createdAt": "2025-07-28T21:05:50.000Z",
    "totalInstallments": 1,
    "timelineException": false,
    "discounts": [
        {
            "type": "NOT_APPLICABLE",
            "value": 0
        }
    ],
    "canceledAt": "2025-08-08",
    "interest": {
        "type": "FIXED_VALUE_PER_DAY",
        "value": 2,
        "startDate": "2025-12-14"
    },
    "fine": {
        "type": "PERCENTAGE",
        "value": 1,
        "startDate": "2025-12-14"
    },
    "automaticBadCreditException": false,
    "anticipation": {
        "isAnticipated": false
    },
    "correlationId": "new-bill",
    "detail": {
        "documentNumber": "teste",
        "externalId": "3444470-a44e-48bc-8b19-6aa244444e32",
        "ourNumber": "74198196346750084",
        "barCode": "2089444444444440001050050014444444410773460",
        "digitableLine": "20890050091963444444444604112940000000105",
        "emv": "00020101021226980014br.gov.bcb.pix2576api-h.developer.btgpactual.com/pc/p/v2/cobv/5b3969415dca40758c8bad8ae849dd64520444444445802BR5925TESTEsao paulo62070503***63044F03"
    },
    "collectionId": "4444bf8b-f0e7-4444-9cd7-c6ef444f2af5",
    "updatedAt": "2025-08-08T19:15:06.000Z",
    "status": "CANCELED"
}